[% setvar title docs/pdds/pdd00_pdd.pod - Parrot Design Documents %]
<div id="archive-notice">
    <h3>This file is part of the Perl 6 Archive</h3>
    <p>To see what is currently happening visit <a href="http://www.perl6.org/">http://www.perl6.org/</a></p>
</div>
<div class='pod'>
<a name='NAME'></a><h1>NAME</h1>
<p>docs/pdds/pdd00_pdd.pod - Parrot Design Documents</p>
<a name='ABSTRACT'></a><h1>ABSTRACT</h1>
<p>This document defines the standard format for the Parrot Design Documents
(PDDs) - the basic descriptions/plans for the design of Parrot.</p>
<a name='DESCRIPTION'></a><h1>DESCRIPTION</h1>
<p>The original intent of the Parrot Design Documents (which themselves were
initially Perl Design Documents) was threefold:</p>
<ul>
<li><a name='1'></a>1</li>
<p>To provide a clear indication of the direction of current development
(essentially, a road map from an abstract idea to a concrete implementation).</p>
<li><a name='2'></a>2</li>
<p>To act as a historical record of the rationale behind the decision, in order
to provide context to future developers, who may not have been familiar
with the original discussion.</p>
<li><a name='3'></a>3</li>
<p>To provide a historical, technical and cultural perspective for future
development work.  Re-implementation or even tangential tasks need only
address what has changed since the original PDD.</p>
</ul>
<p>Needless to say, things didn't work out this way. Some of the context
discussed above is now documented in the <b><i>*.dev</i></b> documents (see the
<b><i>/docs/dev</i></b> directory); much of it remains undocumented. The portions
that have wound up being documented as PDDs are the basic design of
the Parrot interpreter. In other words, the PDDs describe the <b>features
that the interpreter should implement</b>. They <b>should not</b> discuss the
details of the actual implementation (unless they absolutely have to)
or the choices leading to that particular implementation; these are
details that should go in the relevant <b><i>*.dev</i></b> file. On the other
hand, they <b>should</b> detail the trade-offs made in the actual design.</p>
<a name='IMPLEMENTATION'></a><h1>IMPLEMENTATION</h1>
<p>All newly created PDDs will adhere to the PDD standard current as of
the time of proposal. An example of the currently accepted layout is
given in <b><i>docs/pdds/pdd_template.pod</i></b>, which should be used as a
template for any future PDDs.</p>
<a name='FORMAT'></a><h2>FORMAT</h2>
<p>All PDDs will be written in POD parseable by the current stable release
of Perl. Although XML is a viable solution and has its vocal supporters,
and although Parrot is intended to be used by many groups outside of the
Perl community, we have chosen POD for its simplicity and ease of
reading in plaintext form. Conversion to other formats (e.g. HTML) is
encouraged, but the POD version should remain the master copy.</p>
<p>All PDDs will be written in English.  British, American, or Other is
the choice of the author.  Translation to other languages, like all
Perl documentation, is encouraged.  (See <i><a href='#PDD TRANSLATIONS'>&quot;PDD TRANSLATIONS&quot;</a></i>.)</p>
<p>All PDDs will contain the following information:</p>
<ul>
<li><a name='TITLE:'></a>TITLE:</li>
<p>A short, general description of a specific part of the Parrot design.
This may be a particular subsystem (e.g. the garbage collector), or a
more general topic (e.g. basic Parrot datatypes).</p>
<li><a name='VERSION:'></a>VERSION:</li>
<p>Contains current and selected historical metadata on the PDD itself.</p>
<li><a name='CURRENT:'></a>CURRENT:</li>
<p>Contains the following information, current as of the date of
submission.</p>
<ul>
<li><a name='Maintainer'></a>Maintainer</li>
<p>Required.  The name and current email address for the point of
contact for the PDD. This is the person to whom questions, comments,
and patches should generally be addressed. This need not be the author
of the document.</p>
<p>(In practice, non-trivial changes to the PDDs should probably be
discussed on the perl6-internals mailing list before they take place).</p>
<li><a name='Class'></a>Class</li>
<p>Required.  The area of Parrot the PDD covers.  This allows related PDDs
to be logically grouped. The current list of valid classes is:</p>
<pre>    Internals     - on the design of the Parrot interpreter
    Documentation - on Parrot documentation
    Meta          - on the Parrot project as an entity
    Testing       - on the testing of Parrot</pre>
<p>It is expected that most PDDs will fit into a single class, but in
principle a may belong to more than one class. However, peripheral
excursions into the scope of another class should not warrant an
actual classification (i.e. you shouldn't classify something as
<code>Testing</code> simply because you happen to mention potential tests at
one or two points in the text).</p>
<li><a name='PDD Number'></a>PDD Number</li>
<p>Required.  No two PDDs should have the same number. PDD numbers are
assigned by whoever commits the PDDs to the repository, subject to
the approval of the Pumpking.</p>
<li><a name='Version'></a>Version</li>
<p>Required.  A one-up integer reflecting each public revision of a PDD. This
reflects the version of the document itself, and not version of the standard
the document may provide.</p>
<li><a name='Status'></a>Status</li>
<p>Required. The current state of the PDD.  Currently, the only
classifications in use are <code>Informational</code> and <code>Developing</code>.
We hope to eventually add <code>Standard</code>. All three are detailed below:</p>
<ul>
<li><a name='Informational'></a>Informational</li>
<p>A PDD discussing possible design choices for a particular area of Parrot.
This is non-prescriptive -- the final design may look nothing like the
suggested one -- but provides a useful way to document detailed design
concepts for later reference. For a good example, see
<b><i>/docs/pdds/pdd14_bignum.pod</i></b>.</p>
<li><a name='Developing'></a>Developing</li>
<p>An acceptable (at least, in theory) PDD that needs further fleshing out
and fine tuning. The PDD, as well as the implementation it describes, are
both under official development by the Parrot development community.</p>
<li><a name='Standard (Version #)'></a>Standard (Version #)</li>
<p>A frozen snapshot of the design as it applies to Parrot at a particular
moment in time. The version number should reflect that version number
of Parrot that the standard was first applied to. <code>Developing</code> PDDs
are expected to eventually become <code>standard</code>.</p>
</ul>
<li><a name='Last Modified'></a>Last Modified</li>
<p>Required.  The date of the last submission.</p>
<li><a name='PDD Format'></a>PDD Format</li>
<p>Required.  The specific PDD Standard that the PDD adheres to. This allows
scripts to better parse PDDs of multiple aging formats. The format
currently in use is PDD format 1.</p>
<li><a name='Language'></a>Language</li>
<p>Optional.  The language that the PDD is written in.</p>
</ul>
<li><a name='HISTORY:'></a>HISTORY:</li>
<p>A list of free-flow descriptions of significant metadata changes, such
as status changes, or change of maintainers.  Each entry should include
the version, date, and nature of the change.  This provides a quick
historical overview of the major metadata changes of a PDD.  This field is
not to be used for a comprehensive list of alterations to the document.</p>
<li><a name='CHANGES:'></a>CHANGES:</li>
<p>A summary of the changes since the last version.  A comprehensive
change log should be kept, but only within a supporting document.</p>
<li><a name='ABSTRACT:'></a>ABSTRACT:</li>
<p>A quick blurb explaining the purpose of the PDD.</p>
<li><a name='DESCRIPTION:'></a>DESCRIPTION:</li>
<p>A description of the general nature of the PDD and how it relates to
Parrot.</p>
<li><a name='IMPLEMENTATION:'></a>IMPLEMENTATION:</li>
<p>A major section of the PDD that encapsulates a free-form discussion of
any and all applicable information related to the final observations,
conclusions, and what-have-you that required writing the document in
the first place.</p>
<li><a name='ATTACHMENTS:'></a>ATTACHMENTS:</li>
<p>References to supporting files that should be considered part of the
PDD.  Text files and image files may be in any widely accepted format,
which is rather subjective.  Violators may be prosecuted.</p>
<p>Text files and image files should only provide supplemental
information; no fair hiding all the info in an attachment just to not
have to write an implementation section.</p>
<li><a name='REFERENCES:'></a>REFERENCES:</li>
<p>References to additional sources of information, but not those
necessary for the PDD itself.</p>
</ul>
<p>The PDD author may add any additional sections he or she wishes.</p>
<a name='SUBMISSION CRITERIA'></a><h2>SUBMISSION CRITERIA</h2>
<p>Proposed PDDs should be submitted to the perl6-internals mailing list
(located at <a href='mailto:perl6-internals@perl.org'>perl6-internals@perl.org</a>) for discussion, criticism and
general kibitzing. Acceptance of a particular PDD is ultimately up to
the current Pumpking and/or the internals chief (a.k.a. Dan).</p>
<a name='PDD TRANSLATIONS'></a><h2>PDD TRANSLATIONS</h2>
<p>Should a PDD be translated into another language, the following
guidelines should be met.</p>
<ul>
<li><a name='The Maintainer field should reflect who did the translation.'></a>The <code>Maintainer</code> field should reflect who did the translation.</li>
<li><a name='The Version number should match the original document's Version number. Should multiple translated versions of a single original PDD be done (to correct spellings, etc.), the revision specific to that document version should be included in parentheses following the version number.'></a>The <code>Version</code> number should match the original document's <code>Version</code>
number.  Should multiple translated versions of a single original PDD
be done (to correct spellings, etc.), the revision specific to that
document version should be included in parentheses following the
version number.</li>
<li><a name='Attributions in the HISTORY section should be left alone.'></a>Attributions in the <code>HISTORY</code> section should be left alone.</li>
</ul>
<a name='PDD STATUS CHANGES'></a><h2>PDD STATUS CHANGES</h2>
<p>Any change to the status of a particular PDD should be approved by
the current Pumpking and/or the internals chief.</p>
<a name='AVAILABILITY'></a><h2>AVAILABILITY</h2>
<p>All <code>Informational</code>, and <code>Developing</code> PDDs should be readily available,
in a centralized location, to at least the current Parrot development
circles.  All <code>Standard</code> PDDs should be readily available, in a
centralized location, to the general public.</p>
<a name='ATTACHMENTS'></a><h1>ATTACHMENTS</h1>
<p>None.</p>
<a name='REFERENCES'></a><h1>REFERENCES</h1>
<p>Dan Sugalski's original PDD guidelines at
<a href='http://www.mail-archive.com/perl6-internals@perl.org/msg01766.html' target='_blank'>www.mail-archive.com</a></p>
<a name='VERSION'></a><h1>VERSION</h1>
<a name='CURRENT'></a><h2>CURRENT</h2>
<pre>    Maintainer: Simon Glover &lt;<a href='mailto:scog@amnh.org'>scog@amnh.org</a>&gt;
    Class: Meta
    PDD Number: 0 
    Version: 2
    Status: Developing
    Last Modified:  20 February 2004
    PDD Format: 1
    Language: English</pre>
<a name='HISTORY'></a><h2>HISTORY</h2>
<pre>    v2 substantially rewritten on 20 Feb 2004 by Simon Glover
    v1 created on 7 Dec 2000 by BCWarnock &lt;<a href='mailto:bwarnock@raba.com'>bwarnock@raba.com</a>&gt;
    v1 promoted to Developing as PDD 0 on 20 February 2001 by Dan Sugalski.</pre>
<a name='CHANGES'></a><h1>CHANGES</h1>
<pre>    Substantially rewritten to reflect what the PDDs actually are (rather
    than what we hoped they would be 3+ years ago). </pre>
</div>
